NestJS CLI工具使用指南

CLI（Command Line Interface）命令行界面：
│
├── 定义
│   └── 通过终端命令与程序交互的工具
│
├── 优势
│   ├── 快速：自动化重复操作
│   ├── 标准：统一项目结构和代码风格
│   ├── 高效：模板化生成，减少手动创建
│   └── 可靠：避免手动操作的错误
│
└── NestJS CLI 功能
    ├── 创建新项目
    ├── 生成模块/控制器/服务等
    ├── 运行项目（开发/生产模式）
    ├── 构建/测试项目
    └── 代码格式化

# ===== 方式一：全局安装（推荐）=====
npm install -g @nestjs/cli

# 或使用 pnpm（更快）
pnpm add -g @nestjs/cli

# 验证安装
nest --version
# 输出示例：10.3.0

# 查看帮助
nest --help

# ===== 方式二：使用 npx（无需全局安装）=====
npx @nestjs/cli --version

# ===== 方式三：项目本地安装 =====
npm install --save-dev @nestjs/cli

# 使用本地 CLI
npx nest --version

# 查看所有可用命令
nest --help

# 输出示例：
# Usage: nest <command> [options]
#
# Options:
#   -v, --version                                   输出版本号
#   -h, --help                                      显示帮助信息
#
# Commands:
#   new|n [name] [options]                          创建新的 NestJS 项目
#   build [options] [app]                           构建 NestJS 应用
#   start [options] [app]                           启动 NestJS 应用
#   generate|g <schematic> [name] [options]         生成文件
#   info|i                                          显示 NestJS 项目信息
#   add [options] <library>                         安装 NestJS 库
#   update [options]                                更新 NestJS 依赖
#   help [command]                                  显示命令帮助

# ===== 标准用法 =====
nest new project-name

# ===== 简写形式 =====
nest n project-name

# ===== 指定包管理器 =====
nest new project-name --package-manager pnpm
nest new project-name -p pnpm

# ===== 跳过安装依赖（稍后手动安装）=====
nest new project-name --skip-install
nest new project-name -s

# ===== 使用 Git 初始化 =====
nest new project-name --git
nest new project-name -g

# ===== 指定 NPM 镜像源 =====
nest new project-name --registry https://registry.npmmirror.com

# 创建新项目
$ nest new nest-api

# 选择包管理器（交互式）
? Which package manager would you  to use?
 npm
  yarn
  pnpm

# 选择 pnpm 后，CLI 会执行：
#  Installation in progress...
#  Successfully created project nest-api
#  Get started with the following commands:

$ cd nest-api
$ pnpm run start

# 项目创建完成后的目录结构：
nest-api/
├── src/
│   ├── main.ts              # 应用入口
│   ├── app.module.ts        # 根模块
│   └── app.controller.ts    # 根控制器
├── test/                    # 测试文件
├── nest-cli.json            # NestJS CLI 配置
├── tsconfig.json            # TypeScript 配置
├── package.json             # 项目依赖
└── README.md                # 项目说明

# 标准语法
nest generate <schematic> <name> [options]

# 简写形式
nest g <schematic> <name> [options]

# schematic: 模板类型（module、controller、service 等）
# name: 文件名称
# options: 可选参数

# ===== 生成模块 =====
nest generate module users
nest g mo users

# 生成文件：src/users/users.module.ts

# ===== 生成控制器 =====
nest generate controller users
nest g co users

# 生成文件：
# - src/users/users.controller.ts
# - src/users/users.controller.spec.ts（测试文件）

# ===== 生成服务 =====
nest generate service users
nest g s users

# 生成文件：
# - src/users/users.service.ts
# - src/users/users.service.spec.ts（测试文件）

# ===== 生成完整模块（推荐）=====
nest generate module users
nest g co users
nest g s users

# 或者使用 resource（一次性生成所有）
nest generate resource users
nest g res users

# 交互式选择：
# ? What transport layer do you use? REST API
# ? Would you like to generate CRUD entry points? Yes

# 生成的文件：
# src/users/
# ├── dto/
# │   ├── create-user.dto.ts
# │   └── update-user.dto.ts
# ├── entities/
# │   └── user.entity.ts
# ├── users.module.ts
# ├── users.controller.ts
# ├── users.controller.spec.ts
# ├── users.service.ts
# └── users.service.spec.ts

# ===== --dry-run（测试运行，不创建文件）=====
nest g class user --dry-run
nest g class user -d

# 输出示例：
# Generate class with name "user"
# CREATE /src/user/user.ts (23 bytes)
# CREATE /src/user/user.spec.ts (172 bytes)
# DRY RUN MODE enabled! No files were written to disk.

#  用途：预览将要创建的文件，不实际创建

# ===== --no-spec（不生成测试文件）=====
nest g class user --no-spec
nest g class user --spec=false

# 仅创建：src/user/user.ts
# 不创建：src/user/user.spec.ts

# ===== --flat（不创建文件夹）=====
nest g class user --flat

# 创建：src/user.ts（直接在 src 下）
# 而非：src/user/user.ts

# ===== --project（多项目指定）=====
nest g module users --project=api

# 在 monorepo 项目中指定子项目

# ===== --module（自动导入到模块）=====
nest g controller users --module=app

# 自动将 UsersController 导入到 AppModule

# ===== --path（指定路径）=====
nest g module users --path=modules

# 创建：src/modules/users/users.module.ts

# 查看项目环境信息
nest info
nest i

# 输出示例：
#
# [System Information]
# OS Version     : macOS 14.0
# NodeJS Version : v20.10.0
# NPM Version    : 10.2.3
#
# [Nest CLI]
# Nest CLI Version : 10.3.0
#
# [Nest Framework Information]
# packages version path
# @nestjs/common : 10.3.0
# @nestjs/core   : 10.3.0
# @nestjs/platform-express : 10.3.0

# ===== 开发模式（默认）=====
nest start

# ===== 监听模式（热重载）=====
nest start --watch
nest start -w

#  推荐：文件修改自动重启服务

# ===== 开发模式（监听 + 调试）=====
nest start --debug
nest start -d

# ===== 生产模式 =====
nest start --prod

# ===== 指定应用（monorepo）=====
nest start api

# ===== 完整开发命令 =====
nest start --watch --debug

# 或者在 package.json 中：
# "start:dev": "nest start --watch"
# "start:debug": "nest start --debug --watch"
# "start:prod": "node dist/main"

# 构建项目（编译 TypeScript）
nest build

# 指定输出路径
nest build --path=dist

# 指定 webpack 模式
nest build --webpack
nest build -w

# 指定配置文件
nest build --config=nest-cli.json

# 生产环境构建
nest build --prod

# ===== 第一步：创建新项目 =====
nest new user-api

? Which package manager would you  to use? pnpm

# ===== 第二步：进入项目目录 =====
cd user-api

# ===== 第三步：创建用户模块 =====
# 方式一：逐步创建（学习推荐）
nest g module users       # 创建模块
nest g controller users   # 创建控制器
nest g service users      # 创建服务

# 方式二：一次性创建（快速开发）
nest g resource users

? What transport layer do you use? REST API
? Would you like to generate CRUD entry points? Yes

# ===== 第四步：启动项目 =====
pnpm run start:dev

# 服务启动成功：
# [Nest] LOG [NestApplication] Nest application successfully started
# Application is running on: http://[::1]:3000

# ===== 场景：预览将要创建的文件 =====

# 1. 测试创建 class
$ nest g class user -d

# 输出：
# Generate class with name "user"
# CREATE /src/user/user.ts (23 bytes)
# CREATE /src/user/user.spec.ts (172 bytes)
# DRY RUN MODE enabled! No files were written to disk.

# 验证：文件未实际创建
$ ls src/user
# ls: src/user: No such file or directory

# 2. 测试创建不生成测试文件
$ nest g class user -d --no-spec

# 输出：
# Generate class with name "user"
# CREATE /src/user/user.ts (23 bytes)
# DRY RUN MODE enabled! No files were written to disk.

#  仅创建主文件，不创建测试文件

# ===== 场景：创建控制器并自动导入到模块 =====

# 创建 users 控制器，自动导入到 app.module
$ nest g controller users --module=app

# 生成的代码：
# src/app.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users/users.controller';

@Module({
  imports: [],
  controllers: [UsersController],  //  自动导入
  providers: [],
})
export class AppModule {}

# ===== 最佳实践：创建完整模块 =====
# 1. 先创建模块
nest g module users

# 2. 创建控制器（自动导入到 users.module）
nest g controller users --module=users

# 3. 创建服务（自动导入到 users.module）
nest g service users --module=users

DeGit 特点：
│
├──  快速下载
│   ├── 不下载 Git 历史记录
│   ├── 仅下载最新代码
│   └── 速度比 git clone 快 10 倍+
│
├──  用途
│   ├── 下载模板项目
│   ├── 快速启动项目
│   └── 学习优秀项目
│
└──  适合场景
    ├── 下载 starter template
    ├── 下载示例项目
    └── 下载开源项目

# ===== 全局安装 degit =====
npm install -g degit

# 或使用 pnpm
pnpm add -g degit

# ===== 基础用法 =====
degit <repo> [destination]

# repo: GitHub 仓库地址（user/repo）
# destination: 本地目录名（可选）

# ===== 示例：下载 NestJS 模板 =====

# 1. 下载到当前目录
degit nestjs/typescript-starter

# 2. 下载到指定目录
degit nestjs/typescript-starter my-nest-app

# 3. 下载指定分支
degit nestjs/typescript-starter#next my-app

# 4. 下载指定 tag
degit nestjs/typescript-starter#v10.0.0 my-app

# ===== 下载后操作 =====
cd my-nest-app
pnpm install      # 安装依赖
pnpm run start    # 启动项目

# 访问 Awesome NestJS
https://github.com/nestjs/awesome-nestjs

# 模板分类：
├──  Starters（启动模板）
│   ├── typescript-starter（纯 TS）
│   ├── starter（标准模板）
│   └── starters（多种场景）
│
├──  数据库集成模板
│   ├── typeorm（MySQL/PostgreSQL）
│   ├── prisma（现代 ORM）
│   ├── mongoose（MongoDB）
│   └── sequelize（多数据库）
│
├──  技术栈整合模板
│   ├── nest-graphql（GraphQL）
│   ├── nest-microservices（微服务）
│   ├── nest-websocket（WebSocket）
│   └── nest-redis（Redis）
│
└──  示例项目
    ├── realworld-example-app（完整应用）
    └── nest-typescript-starter（最佳实践）

# ===== 第一步：在 Awesome NestJS 中搜索 TypeORM =====
# 访问：https://github.com/nestjs/awesome-nestjs
# 搜索：typeorm

# ===== 第二步：选择模板 =====
# 找到：nestjs/typeorm-starter
# GitHub 地址：https://github.com/nestjs/typeorm-starter

# ===== 第三步：使用 DeGit 下载 =====
degit nestjs/typeorm-starter nest-typeorm-demo

# 输出：
# > cloned nestjs/typeorm-starter#HEAD to nest-typeorm-demo

# ===== 第四步：安装依赖 =====
cd nest-typeorm-demo
pnpm install

# ===== 第五步：配置数据库 =====
# 编辑 .env 文件
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=password
DB_DATABASE=test

# ===== 第六步：启动项目 =====
pnpm run start:dev

# ===== 第七步：查看项目结构 =====
nest-typeorm-demo/
├── src/
│   ├── app.module.ts       # 根模块（含 TypeORM 配置）
│   ├── user/               # 用户模块
│   │   ├── user.entity.ts  # 实体
│   │   ├── user.module.ts  # 模块
│   │   ├── user.controller.ts
│   │   └── user.service.ts
│   └── main.ts
├── .env                    # 环境变量
├── ormconfig.json          # TypeORM 配置
└── package.json

# ===== 下载 Prisma 集成模板 =====
degit nestjs/prisma-starter nest-prisma-demo

cd nest-prisma-demo
pnpm install

# 配置数据库
# 编辑 .env
DATABASE_URL="mysql://root:password@localhost:3306/test"

# 初始化 Prisma
npx prisma generate
npx prisma db push

# 启动项目
pnpm run start:dev

# ===== 速度对比测试 =====

# Git Clone（包含历史）
$ time git clone https://github.com/nestjs/nest.git
# real    0m45.123s

# DeGit（仅最新代码）
$ time degit nestjs/nest nest-demo
# real    0m3.456s

# 速度提升：约 13 倍

# ===== 完整流程 =====

# 1. 创建新项目
nest new my-project
# 选择 pnpm 作为包管理器

# 2. 进入项目
cd my-project

# 3. 创建核心模块
nest g module auth          # 认证模块
nest g module users         # 用户模块
nest g module posts         # 文章模块

# 4. 创建每个模块的控制器和服务
nest g controller auth --module=auth
nest g service auth --module=auth

nest g controller users --module=users
nest g service users --module=users

nest g controller posts --module=posts
nest g service posts --module=posts

# 5. 创建公共模块
nest g module common
nest g module config

# 6. 创建守卫、管道、拦截器
nest g guard auth/common/guards
nest g pipe validation/common/pipes
nest g interceptor logging/common/interceptors

# 7. 创建 DTO
nest g class dto/create-user.dto --flat
nest g class dto/update-user.dto --flat

# 8. 安装常用依赖
pnpm add @nestjs/config          # 配置管理
pnpm add @nestjs/jwt             # JWT 认证
pnpm add @nestjs/passport        # 认证中间件
pnpm add @nestjs/typeorm typeorm mysql2  # 数据库
pnpm add class-validator class-transformer  # 验证

# 9. 安装开发依赖
pnpm add -D @types/node

# 10. 启动项目
pnpm run start:dev

# ===== 快速启动流程 =====

# 1. 从模板创建项目
degit nestjs/typeorm-starter my-api

# 2. 安装依赖
cd my-api
pnpm install

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 4. 初始化数据库
npx typeorm migration:run

# 5. 启动项目
pnpm run start:dev

# 6. 访问 Swagger 文档
open http://localhost:3000/api

# ===== 创建 Monorepo 项目 =====

# 1. 创建主项目
nest new my-monorepo

# 2. 创建子应用
cd my-monorepo
nest generate app api
nest generate app admin

# 3. 创建公共库
nest generate library common
nest generate library config

# 4. 项目结构
my-monorepo/
├── apps/
│   ├── api/              # API 应用
│   │   ├── src/
│   │   └── nest-cli.json
│   └── admin/            # 管理后台应用
│       ├── src/
│       └── nest-cli.json
├── libs/
│   ├── common/           # 公共库
│   │   └── src/
│   └── config/           # 配置库
│       └── src/
├── nest-cli.json         # CLI 配置
└── package.json

# 5. 运行指定应用
nest start api
nest start admin

# 6. 构建指定应用
nest build api
nest build admin

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true,
    "assets": ["**/*.proto"],
    "watchAssets": true
  },
  "generateOptions": {
    "spec": true,
    "flat": false
  },
  "projects": {
    "api": {
      "type": "application",
      "root": "apps/api",
      "entryFile": "main",
      "sourceRoot": "apps/api/src",
      "compilerOptions": {
        "tsConfigPath": "apps/api/tsconfig.app.json"
      }
    },
    "common": {
      "type": "library",
      "root": "libs/common",
      "entryFile": "index",
      "sourceRoot": "libs/common/src",
      "compilerOptions": {
        "tsConfigPath": "libs/common/tsconfig.lib.json"
      }
    }
  }
}

NestJS 开发工作流：
│
├──  项目初始化
│   ├── 学习：nest new + 逐步创建模块
│   └── 生产：degit + 官方模板
│
├──  模块开发
│   ├── 创建模块：nest g module <name>
│   ├── 创建控制器：nest g controller <name>
│   ├── 创建服务：nest g service <name>
│   └── 创建 DTO：nest g class dto/xxx.dto
│
├──  快速开发
│   └── 完整资源：nest g resource <name>
│
└──  调试运行
    ├── 开发模式：pnpm run start:dev
    └── 调试模式：pnpm run start:debug

# ===== 项目管理 =====
nest new <name>                    # 创建新项目
nest info                          # 查看项目信息
nest update                        # 更新 NestJS 依赖
nest add <library>                 # 安装 NestJS 库

# ===== 构建与运行 =====
nest build [app]                   # 构建项目
nest start [app]                   # 启动项目
nest start --watch                 # 监听模式
nest start --debug                 # 调试模式
nest start --prod                  # 生产模式

# ===== 文件生成 =====
nest generate <schematic> <name>   # 生成文件
nest g <schematic> <name>          # 简写形式

# ===== Monorepo =====
nest generate app <name>           # 创建应用
nest generate library <name>       # 创建库

# ===== 帮助 =====
nest --help                        # 查看帮助
nest <command> --help              # 查看命令帮助